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PREFACE 


This book is a reference guide to use when programming with 
Microsoft Basic on your HHC™. It provides detailed informa- 
tion that you can refer to as you write programs. 


The companion volume to this manual is the Microsoft Basic 
Tutorial, which teaches you how to program in Microsoft 
Basic. 


If you are familiar with the HHC, but not with Basic, you 
can skim over the sections of the book that are marked with 
{H}. 

If you are familiar with both Basic and the HHC, and only 
need to know how Microsoft Basic on the HHC differs from 
other Basics, you can skim over most of the book; pay atten- 
tion to the sections that are marked with {B}. 


This book presents examples of the characters exactly as 
they appear on the HHC display. We have used the ® symbol 
to indicate when a one-line display is continued on the follow- 
ing line in the example. 
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CHAPTER 1: STATEMENTS AND 
COMMANDS 


Below is a complete description of every statement and 
command that Microsoft Basic accepts. In describing the 
syntax of the statements and commands, we will use the 
following notation: 


e@ Upper case letters should be used as shown. 


e Lower case letters are “placeholders” for something you 
must fill in when you write the statement. 

e ‘[x]’ means “x is optional.” 

@ ‘[xlyiz] means “you may choose one of x or y or z, or you 
may omit this expression.” 

e ‘{xlyiz}’ means “you must choose one of x or y or z.” 


n represents a numeric value (constant, variable, 
expression, etc).!1} 

nv represents a numeric variable or array element. 

nc represents a numeric constant. 

Ss represents a string value. 

SV indicates a string variable. 

sc represents a string constant. 

Xx represents a value of either numeric or string 
type. 

v represents a variable of either numeric or string 
type. 

In represents a line number. 


Where we need more than one element of the same type, 
we will add numbers to the names: e.g.,n1, n2, n3,... 

? 

See PRINT. ‘?’ is an abbreviation for PRINT. 


Examples: 


POI 


“Fue | eff iciermode ata “py 











‘) - Integer and numeric values are interchangeable, except where 
noted otherwise. 
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ASSIGNMENT 


Format: [LET] nv = n 
or [LET] sv = s 


The value of the expression nor sis assigned to the variable 
nvor sv$. 


The reserved word LET is allowed for compatibility with 
some other versions of Basic, which require it. An assign- 
ia Statement has the same effect whether or not LET is 
used. 


Examples: 


LET #5 
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ATTACH 


Format: ATTACH n1 TO #n2 


Attaches a device with device code n7? to LUN (logical unit 
number) n2. 


Valid values of n7 for each peripheral are given in Chapter 7. 


Valid values for n2 are 0 through15.0is the system input unit, 
normally attached to the keyboard. 1 is the system output 
unit, normally attached to the LCD. 2 through 15 have no 
“normal” attachments; you must attach devices explicitly 
before you can use them. 


Examples: 
ATTACH Bo TO #2 
ATTACH Un TO #e+8e 
ATTACH DTH To #3 


BYE 
Format: BYE 


BYE returns you from the Basic interpreter, which allows you 

to edit and run a program, to the Basic menu, which allows 

you to chose a program to edit and run, and to use the I/O 

and HELP keys. 

Always use BYE to return from the Basic interpreter to the 

Basic menu. If you use the CLEAR key, the HHC’s memory 

area will appear to be full, and you will be unable to run or 

edit any Basic program. 

lf you accidentally use CLEAR to leave the Basic interpreter, 

use the following procedure to restore the file system: 

1. Return to the primary menu. 

2. Select the file system. 

3. Delete the file named B from intrinsic RAM (select B from 
the file system’s menu and delete its name). 

4. Leave the file system and select Basic from the primary 
menu. 

5. Select the file you were editing when you pressed 
CLEAR. 

6. Save the file with BYE. 


{B} 


{B} 


(By) CALL DATA 


Format: CALL n 


CALL calls a subroutine written in 6502 machine language 
(not written in Basic). 


nis the address of the subroutine’s entry point in the HHC’s 
memory. nm must be in the range 0 to 65535. 


If you are familiar with 6502 machine language, Basic’s use 
of memory and the HHC’s internal operations, you can 
perform functions that are not otherwise availabie in Micro- 
soft Basic by POKEing machine language subroutines into 
the HHC’s memory and CALLing them. 


Caution! Using an invalid value for nm can have catastrophic 
effects on your program and any other programs or data in 
the HHC’s storage. 


{B} CLEAR 


Format: CLEAR 


The CLEAR statement does the following things: 
® Sets all numeric variables to zero and all string variables 
to null. 


@ Erases the index, step and limit of any active FOR/NEXT 
loop, and the return pointer of any active GOSUB. 
@ RESTOREs the program's DATA statements, if any. 


Note that the CLEAR statement has no connection with the 





Format: DATA v1 [, v2, v3, . . .,.vn] 


where each vis a numeric value or string value. 


Contains data which a READ statement can read. See 
READ for details of use. 


A DATA statement may be inserted anywhere in your pro- 
gram; flow of control goes around it. 


DATA is legal in immediate mode, but it has no purpose 
there. 


About Siring Values 
If a string value contains a comma, it must be enclosed in 
quotation marks: 


DATA | 


PIPE 





"RETE. ART BLUE OBL 
otf 


sET, 
JE AMT) BLE” 


A string value containing lower case letters must also be in 
quotes, or Basic will shift the letters to upper case when it 
stores the DATA statement. 


A string value with leading or trailing blanks need not be in 
quotes. READ does not trim the blanks when it reads the 
value. 


A quotation mark that appears after the first character in a 
string value is treated as a character in the value like any 
other. 


HHC’s CLEAR key. Examples: 
; ; TITRA BE. 1a. 3. G. is 
CONT (immediate mode only) vane 
Format: CONT DATE 
} Use CONT to restart a program after you have interrupted it tate wake 


by pressing the C1 key, or after it has executed a STOP or 
END. 


You may display and change the values of variables while 
the program is interrupted. Except for the changes you 
make, the program will be in the same state when you 
CONTinue it as it was in when it stopped. 


You may not CONTinue a program after an error has 
occurred; after you have edited the program; or before you 
have begun RUNing the program. 
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DEF (deferred mode only) 
Format: DEF FN mm(pr) = ex 


DEF defines a function named mm. mm may be any name 
that would be valid as the name of a numeric variable. (But 
the name of a function is distinct from the name of a numeric 
variable or array; you can use the same name for both, and 
Basic will always know the difference by context.) 


pr is the function’s formal parameter. It may be any name 
that would be valid as the name of a numeric variable. (But 
the names of a numeric variable and a formal parameter are 
distinct.) 


ex is the body of the function definition. If it contains 
references to pr, they refer to pras a formal parameter, not 
as a variable (if there is also a variable named pr). 


When you refer to the function later in your program, Basic 
does the following: 
1. Calculates the value of the function reference’s argument. 


2. Substitutes that value for the pr wherever pr appears in 
ex. 


3. Evaluates ex. 


4. Returns the value of ex as the value of the function 
reference. 


Examples of definitions: 


HEP FR RRO ihe | 





FE OFH YWYeZa=44+ LEH oST#> 


Examples of use: 


PRIAMT FM FRM 


PRINT MEFH GON~23 
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DIM 


Format: DIM xa(n1 [, n2,. . .nx]) 
or DIM xa$(ni[, n2,. . .nx]) 


Defines an array with x dimensions. The array has n1 
elements along its first dimension, n2 elements along its 
second dimension, and so forth. 


Array elements are numbered from 0; thus, the array’s 
elements are numbered 0 to n1-1 along the array’s first 
dimension, and so forth. 


You can define more than one array in one DIM statement. 
Separate the array definitions with commas. 


If you refer to an array without first defining it with DIM, Basic 
automatically defines it as an array with one dimension and 
10 elemenis. 


Examples: 

TIM Boies 

DIM ANECS. Bo 

THM Scho VARS 
END 
Format: END 


END terminates execution of your program. Unlike STOP it 
does not display a “Break in nnnn’ message. 


Examples: 
ERT 
IF =e THEM EHT 
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FOR 
Format: FOR nv=ni TO n2 [STEP n3] 


FOR begins a FOR/NEXT loop. 


Basic executes the statements between FOR nv=...’ and 
‘NEXT x’with nv=n1, then with nv=n1+4+ n3, then with 
nv=n1+2*n3 etc. Basic stops looping after the last pass for 
which nv< = n2. 


lf n3 is absent, Basic assumes n3=1. 


If n3<0, Basic stops the loop after the last pass for which 
nv> =n2. 


Terminology 

nv is called the index of the loop. 

n1 is called the initial value of the loop. 

n2 is called the limit of the loop. 

n3 is called the step or increment of the loop. 


Note On Ending a Loop 

You may leave a FOR/NEXT loop by doing a GOTO if you 
wish. If you do, the final value of the index will be the value it 
had the last time through the loop. If you allow a FOR/NEXT 
ioop to end naturally, the final value of the index will the the 
value it had the last time through the loop, plus the step. 


Note that a FOR/NEXT loop always executes at least once, 
even when the initial value is past the limit. 


Notes On NEXT 


You may end two or more loops at the same point by putting 
both of their subscripts in the same NEXT, innermost sub- 
script first, like this: 


begins outer loop 





begins inner loop 





ends both loops 
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lf you want to write a NEXT that terminates only the 
innermost loop (or if there is only one open locp it could 
apply to), you may omit the index completely: 


begins loop 





ends loop 


No-Nos 


If two or more FOR/NEXT loops are nested and they all end at 
the same point, you must end every loop in a NEXT state- 
ment: 





begins outer loop 





begins inner loop 





does not end both loops 


oe doing the following things when you write FOR/NEXT 
oops: 


@ Changing the limit or step after the start of the loop. (The 
change will not affect the execution of the loop.) 
@ Entering a loop by executing a GOSUB, GOTO, or IF ... 
t THEN instead of executing FOR. (You'll get an NF error 
. when you execute the NEXT.) 
You may always leave a FOR/NEXT loop with a GOSUB, 
then RETURN into it. You may also leave a FOR/NEXT 
loop with a GOTO, then return to it with a GOTO, but that 
is not good practice; it is difficult to follow and is liable to 
give rise to programming errors. 
e Changing the value of the index inside the loop. (It works 
in this Basic, but may not work in others, and it is 
generally a bad practice.) 


e aon an integer variable for the index (you'll get an SN 
error). 











ee Be Examples: 
BET CHE 
GET de. CHS 





GET #OMa OME 








es OR Imk¢a> TO 
“oo GOSUB 
Format: GOSUB In 
{B} GET Calls a subroutine; transfers control to the first statement on 


line number Jn. Executing a RETURN will return control to 


Format: GET [#n,]sv the next statement after the GOSUB. 


or GET [#n;]sv 


Example: 
The two forms of GET shown above are completely equiva- - COSUE Taide 
| ent. Siok ee Oe LR deo 
Inputs one character from LUN (logical unit number) n and 
assigns it to string sv. 
If the LUN is omitted, Basic assumes #0 (normally the 
keyboard). 
If the LUN is #0, Basic does not echo the character on the GOTO 


LCD, as it would for INPUT. 


The ENTER key counts as an input character like any other. 
So do all of the other “non-character” keys except ON, OFF, 
CLEAR, which have their usual functions, and SHIFT and 
2nd SFT, which apply to the next key pressed as usual. 


Note: there are two restrictions on your use of the keyboard 


Format: GOTO In 


Transfers control to the first statement on line number In. 


when you are using GET. First, GET does not “read” Example: 
function key definitions correctly. It misses a keystroke for ; 
every program line that is executed between one GET and 7 GOTO FS 


the next. Second, GET does not read keyboard characters 
correctly if you “type ahead” of the program; again, it misses 
a keystroke for every program line that is executed between 
one GET and the next while keystrokes are waiting to be 
read. 


a See oo 
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IF 


Format: IF logical-expression GOTO In 
or IF logical-expression THEN stmit{:stmt. . .stmt] 


Evaluates logical-expression. logical-expression is 
usually an expression involving a logical operator like ‘<’ or 
‘>=', but it may be any expression ihat evaluates to a 
numeric value. 


If fogical-expression has a non-zero value, IF does a 
GOTO to Jn, or executes each stmt from THEN to the end of 
this line. 


\f logical-expression has a zero value, IF does nothing. 


Examples: 








INPUT (deferred mode only) 
Format: INPUT [#n, ][““prompt’;]v1,v2,v3,. . . 


Reads a line of input from the keyboard or from a peripheral. 


nis the LUN to read from. If nis omitted, Basic assumes LUN 
#0 (the keyboard). 


“prompt” is a prompting message. If it is present, INPUT 
prompts the user with this message, suffixed with a ‘?’. If 
“prompt” is absent, INPUT prompts the user ‘?’. 


“prompt” must be a string constant. if you use a string 
variable, INPUT will try to read into the variable. If you use an 
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expression, you will get an SN error. 


v1, v2, v3,... are the variables to be read. Each of them may 
be numeric, integer, or string. 


(INPUT reads values into the variables in the order that the 
variables appear in the statement. A value may be terminated 
by a comma or end-of-line; except that if a value read into a 
string variable begins with a quotation mark, it is terminated 
only by a second quotation mark or end-of-line. 


If INPUT receives too few values on the keyboard, it prompts 
the user for additional values with ‘??’. If it receives too few 
values from a peripheral, it simply reads another record. If 
input receives too many values from the (last) input line or 
record that it reads, it discards the extras. Note that this is 
different from the behavior of READ, which saves the extras 
for the next READ. 


Examples: 














LET 


See Assignment. LET is equivalent to an assignment state- 
ment. 
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{B} LIST 


Format: LIST 
or LIST #n 
or LIST In 
or LIST #n,In 


LIST begins listing the program you are editing at line In. If In 
is not given, LIST begins listing the program at its first line. 


nis the LUN the list should go to. If n is not given, Basic 
assumes LUN #1 (normally the LCD). 


Interacting With LIST 


When you enter LIST and press RETURN, LIST displays the 
first line you have requested. (If you are listing on a device 
other than the LCD, you may have to press # to see the first 
line.) 


If the line is too long to fit on the LCD, LIST displays its 
beginning, and then rotates it until the end becomes visible. 
To stop the rotation before the end becomes visible, press 
any key. 


To see the secondline, press #. To see the third line, press » 
again, and so on. When you press # after seeing the last line, 
LIST ends.'?} 


To end LIST at any point, press ENTER instead of #. 


To edit a line, LIST the line and use the editing keys (see 
Chapter 6) as necessary. When you are done editing the line, 
press ENTER. LIST stores the changed line in your program 
and ends. You must use LIST again to see and edit more of 
your program. 


If you begin editing a line and then decide not to change it 
after all, press the * key. Basic will list the next line without 
storing the changed line in your program. 


Note On Deferred Execution 


You can use LIST in a program, but when you are done 
executing LIST your program will end. In other words, LIST 
behaves as though an END statement were built into it. 





2}. Unlike the HHC’S file system editor, the Basic editor only lets you 
move down in a file. You cannot use the key to move up. 
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NEW 
Format: NEW 


NEW does the following things: 


@ Sets all numeric variables to zero and all string variables to 
null. 


e Erases the index, step and limit of any active FOR/NEXT 
loop, and the return pointer of any active GOSUB. 


e Deletes all the lines from the program. 


Since NEW deletes all the lines from your program, and {B} 


affects the program stored in the memory area as soon as itis 
entered, you should use the statement very cautiously. 


NEXT (deferred mode only) 


Format: NEXT 
or NEXT nv 
or NEXT nvx,... ,nv2,nvt 


Ends a FOR/NEXT loop. 


nvis the index of the loop being ended. If nvis omitted, NEXT 
ends the innermost loop now open. If severalnv 's are used 
on one NEXT, the one closing the innermost loop must be 
first. 


For more information, see the description of FOR. 











ON 


Format: ON n GOTO In1,In2,. . .,[Inx 
or ON n GOSUB In1,In2,. . .,Inx 


Evaluates n and truncates the result to the next lower integer 
if necessary. If n<1 or n>x, ON does nothing (i.e., the next 
sequential statement is executed). If n= 1, ON does a GOTO 
or GOSUB to 7n7. If n=2, ON does a GOTO or GOSUB to 
1n2, and so forth. 


Examples: 





POKE 
Format: POKE n1,n2 


Stores n2 in the HHC’s memory at the memory address n1. 


n1 must be in the range 0 to 65535. n2must be in the range 0 
to 255. 


Caution! Since POKE stores data directly into the HHC’s 
memory, there is no checking to prevent you from POKEing 
data into the wrong place. If you use POKE with improper 
values for n7 or n2, the results will be unpredictable, and can 
be catastrophic. See the chapter on PEEK and POKE in the 
Microsoft Basic Tutorial Guide for more information. 


For a discussion of useful PEEK and POKE addresses, see 
Chapter 8. 
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PRINT 


PRINT [#n,] x1 4,13} x2 Gls... xy [,13} 
Format: 
2 [#n] 


‘?’ ig an abbreviation for PRINT. If you enter ‘?’ in a statement, 
Basic will display ‘PRINT’ when you LIST the statement. 


PRINT writes information to the LUN (logical unit number) 
specified by n. lf nis absent, Basic assumes LUN #1 (nor- 
mally the LCD). 


How Values Are Positioned 


Each x is a numeric or string expression. PRINT writes the 
values of the expressions in the order they appear in the 
statement. 


PRINT divides the output line into zones, each 16 characters 
long. The first xis displayed at the beginning of the first zone. 


If the first and second x’s are separated by a semicolon, 
Basic puts no spaces between them. (But recall that a space 
is displayed at the end of a numeric value, as part of the 
value.) If the first and second x’s are separated by a com- 
ma, Basic skips to the beginning of the next zone before 
displaying the second value. 


If the last xis followed by a semicolon, Basic does not end the 
line; the next PRINT statement will add data to the end of the 
same line. If the last xis followed by a comma, Basic does not 
end the line, but skips to the start of the next zone. If the last x 
is followed by neither a semicolon nor a comma, Basic ends 
the line, so that the next PRINT statement will begin writing 
data at the start of the next line. 


Basic has two special functions, SPC and TAB, which may be 
used only as PRINT statement expressions. SPC (N) inserts 
N spaces in the output line. TAB (N) advances the cursor to 
column N; if the cursor is already at or past column N, TAB 
does nothing. 


PRINT With No Values 
A PRINT statement may have no x’s, like this: 





or 





417 


Such a PRINT statement writes a blank line, or ends the 


current line of output if the previous PRINT statement ended 
with a semicolon or a comma. 


Miscellaneous Notes 


The character that separates the LUN from the first x may be 
either a comma or a semicolon. The two are equivalent in this 
context. Since they come before the first x, they have no 
effect on the output. 


Examples: 

















tit TET 
eh ETE 





READ 
Format: READ v1 [,v2, v3... ., vn] 


READ reads data from one or more DATA statements. 


Data items are read from DATA statements left-to-right and 


from the beginning of the program to the end. One item is read 
for each of the variables v1, v2, v3, .. . 


lf a READ runs out of data in one DATA statement, it begins 
reading the next. If a READ has data left over when it is done 


reading into its variables, it leaves the data for the next READ 
to get. 
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Examples: 








REM 
Format: REM followed by a remark of any sort. 


REM begins a remark line. A remark line may be used to 
include any sort of useful information in a program, such as 
the name of the author, purposes of the variables, or notes 
about how the program works. 


Basic inserts a space between REM and the beginning of the 
remark. Thus, if you enter this, 





Basic will store this: 





t 


and if you enter this, 





Basic will store this: 





(with two blanks after the REM). 


Note that REM turns an entire Jine into a remark. The remark 
is not terminated by a colon, as conventional Basic state- 
menis are. 


Examples: 








RESTORE 
Format: RESTORE 


“Rewinds” the program's DATA statements so that next 
READ statement will read the first data item on the first DATA 
statement. 


RETURN 
Format: RETURN 


Returns control from a subroutine to the statement after the 
most recent GOSUB not yet RETURNed from. 


STOP 
Format: STOP 


Interrupts execution of the Program and displays the mes- 
sage 
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on the LCD. (nnnnis the line number of the line the STOP is 
on.) 


After STOPing a program, you can continue it with the CONT 
statement. See CONT for more information. 


TROFF 
Format: TROFF 


Turns off the program execution trace that is turned on by 
TRON. 


TRON 
Format: TRON 


Turns on Basic’s execution trace facility. When the trace 
facility is on, Basic displays the line number of each statement 
that it executes in deferred mode. The trace display looks like 
this: 





where each nnis the line number of one line in the program. 


Once the trace facility is turned on, it remains on until it is 
turned off by TROFFE or until you return to the Basic menu with 
BYE. 
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CHAPTER 2: INTRINSIC FUNCTIONS 


ARITHMETIC FUNCTIONS 


nv = ABS (n) 
Returns the absolute value of n. 


nv = EXP (n) 


Returns the constant E (2.71828183) raised to the power 
n. The maximum value of n that will not produce an over- 
flow error is 88.02969. 


nv = FRE (n) {B} 


Returns the number of free bytes of memory available for 
storing and running programs. This is the size of the cur- 
rent memory area, minus the amount of space already 
occupied by programs and data. n is ignored. 


nv = INT (n) 


Returns the largest integer nvsuch that n< = nv. INT(1.1) 
is 1; INT(1) is 1; INT(.9) is 0; INT(-.1) is -1. 


nv = LOG (n) 


Returns the the natural (base E) log of n. To obtain the 
base Y log of X, use the formula LOG(X)/LOG(Y). 


Example: the base 10 (common) log of 7 is LOG(7)/ 
LOG(10). 


nv = PEEK (n) 


Returns the value stored at memory address n. n must be 
in the range 0 to 65535. nvis in the range 0 to 255. 


nv = POS (n) 
Returns the length of the current output line. 


if you execute POS immediately after ending a line of 
output or PRINTing a carriage return, POS returns the 
value 0. PRINTing a printable character (code #32 or 
greater) adds 1 to the value POS will return. PRINTing a 
control character has no effect on the value. 


The value of POS is affected by output on the LCD and on 
every peripheral. For example, if you execute the following 
code: 
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sv = CHR§(n) 


Returns the character that is represented by the number n 
in ASCH notation. For example, CHR$(71) is ‘G’; 
CHR$(33) is ‘!” 


If n<O or n> =256, CHR$ gives an ‘FC error’. 





the value returned by POS will be 7, even though the 
lengths of the current output lines on the LCD and LUN #2 
are 3 and 4, respectively. Thus, you must avoid doing 
output on one LUN while building up a line of output on 
another if you want POS to have meaning. 


sv = LEFTS§(s,n) 


Returns a string value consisting of the first n characters of 
Ss. 


lf nis not an integer, LEFT$ truncates it. 

If nis zero, LEFT$ returns the null string. 

If n>LEN(s), LEFT$ returns s. 

If n<O or n> =256, LEFTS$ gives an ‘FC error’. 


nv = RND (n) 
Returns a “random” number in the range O0< = RND(n)<1. 


The first time you call RND, use a negative n. This makes 
RND use nas a “seed” to begin generating a random 
number sequence. The same seed always produces the 
same sequence. RND returns the first number in the sequ- 
ence. 


On subsequent calls to RND, use a positive n. This makes 
ND return the next random number in the sequence. 


Using a zero value for nm makes RND return the same 
random number it returned the preceding time it was cal- 
led. This is sometimes more convenient than saving the 
last value in a variable. 


nv = LEN (s) 
Returns the length, in characters, of the string s. 


sv = MID&(s,n1,n2) 


Returns a substring of s beginning at the n7’th character, 
n2 characters long. 


If 7 is 1, the substring begins at the first position in s; if nis 
2, the substring begins at the second position in s; and so 
forth. 


lf nf is not an integer value, MID$ truncates it. If 
n1>=LEN(s), MID$ returns the null string. If n7<0 or or 
n1>=256, MID$ gives an ‘FC error’. 


lf n2=0, MID$ returns the null string. If n2 is greater than 
number of characters remaining in the string from charac- 
ter n7 to the end, MID$ returns the entire part of the string 
from character n7 to the end. If n2<0 or n2> = 256, MIDS 
gives gives an ‘FC error’. 
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nv = SGN (n) 
Returns the sign of m: 1 if n>0, 0 if n=O, -1 if n<0. 


nv = SQR (n) 


Returns the square root of n. Equivalent to n>. Causes an 
“FC error’ (“illegal quantity error’) if n<O. 


SQR(N) produces the same result as N-, but executes 


more quickly. sv = RIGHTS(s,n) 


Returns a string value consisting of the last n characters of 


s. 
STRING FUNCTIONS RIGHT$ treats unusual values of n the same way that 
LEFT$ does. 
eae sv = STR$(n) 


Returns the number that represents the character s (the 
first character of s, if sis more than one character long) in 
ASCII notation. For example, ASC(‘G") returns 71; 
ASC(“!”) returns 33. 


If s is the null string, ASC gives an FC error. 


Returns the value of n, converted to a string. For example, 
STR$(71) is ‘71’. 


STR$ uses the same conversion rules that the PRINT 
statement uses when it displays a numeric value. 


2-2 2-3 


POHAAAHAIHFHH HAS 


|. 


nv = VAL (s) 


Returns the value of s, converted to a number. For exam- 
ple, VAL(‘71’) is 71. 

VAL uses the same conversion rules that the INPUT state- 
ment uses when it reads a numeric value. If the string value 
cannot be interpreted as anumber, VAL ignores everything 
from the first invalid character to the end of the string. Thus 
VAL(5X”) returns the value 5; VAL(“FGHRTY”) returns 
the value 0. 


Note that VAL, like INPUT, considers a lower case ‘e’ to be 
an invalid character in a number expressed in scientific 
notation. For example, ‘2.5E3’ is valid; ‘2.5e3’ is invalid, 
and will return the value 2.5. 


FUNCTIONS THAT MAY BE USED ONLY AS 
PRINT VALUES 


SPC (n) 
Prints nm spaces. 
If <0 or n> =256, SPC gives an ‘FC error’. 


TAB (n) 


Inserts enough spaces before the following value to make 
the value begin in column n. If the displayed line is already 
filled up to or beyond column n, TAB does nothing. 


If n<O or n> = 256, TAB gives an ‘FC error’. 


TRIGONOMETRIC FUNCTIONS 


Microsoft Basic on the HHC does not have built-in trigo- 
nometric functions. You can use the following subroutines to 
calculate trigonometric functions if you need them. 


These subroutines are based on procedures described in 
Software Manual for the Elementary Functions, by Cody 
and Waite.'?’ 


The Functions 


The trigonometric functions implemented by these sub- 
routines are: SIN, COS, TAN, COTAN, ATAN (arctangent) and 
ATAN2 (another version of arctangent). 





"}. Software Manual for the Elementary Functions , Cody, William J., 
Jr., and Waite, William. Prentice-Hall, Inc., Englewood Cliffs, Nu, 
1980. 
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SIN, COS, TAN and COTAN expect an angle, in radians, in the 
variable TX. They return the result in TR. 


The functions reduce large angles to the smallest possible 
range before evaluating a function. Very large angles cause 
the functions to lose precision, since such large numbers 
cannot be represented as precisely as small ones. See Cody 
and Waite for details. 


ATAN expects a scalar input value in TX. It returns its result, in 
radians, in TR. 


ATAN2 expects two inputs in TU and TV. It returns its result, in 
radians, in TR. ATAN2 calculates the angle between the posi- 
tive u-axis and the directed line segment to the point (TU, TV). 


If TU is zero and TV is non-zero, ATAN2 is defined to be + pi/2. 


Constants and Variables 


The subprograms use variables beginning with the letter K to 
refer to constant values. This speeds up execution signifi- 
cantly, since interpreting numeric constants is Microsoft 
Basic’s slowest operation by a large margin. 


All “non-constant variables” in the subprograms begin with 
the letter T. 


Most of the “constant variables” are preceded by remarks 
that list the corresponding values in the Cody and Waite 
algorithms. Note that Cody and Waite sometimes use the 
same names, such as C1, C2, C3, ..., for different constants 
in different pairs of functions. The subprograms store these 
constants in distinct variables. 


The table below shows how the names of “non-constant 
variables” correspond to the names used in Cody and Waite’s 
flowcharts. 


SIN and COS 


variable 


(g) & result 
GN 
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TAN and COTAN 





variable use 
TF f 
TN XN 
TR result 
TS XNUM 
TT g & XDEN 
TX X 
ATAN and ATAN2 
variable use 
TF f; exponent of TV 
TN N; exponent of TU; internal-format 
exponent of most numeric variable 
most recently referred to 
TR result 
TU U 
TV Vv 
TX Xx 
TY g & R(g) 
Separability 


The subprograms are divided into three groups: SIN/COS, 
TAN/COTAN, and ATAN/ATAN2. Each group is independent of 
the others, and may be used alone. 


The initialization section is sub-divided by the subprograms 
that the constants serve. If you include only one or two of the 
subprograms in a given program, you may include only the 
constants used by those subprograms. But note that some 
constants serve more than one pair of functions; these con- 
stants are listed separately from the others. 


1100 FC$ = “ FC ERROR” 

1200 REM ***FOR ALL FUNCTIONS*«« 
1210 REM EPS 

1220 KF = 2E-16 

1230 REM ***SIN/COS & ATAN/ATAN2+*« 
1240 REM Pl/2 

1310 KA = 1.57679633 

1320 REM ***SIN/COS««* 

1330 KB = INT (3.14159265 » 2 A 16) 
1340 REM 1/PI 

1350 KC = .318309886 

1360 REM C1 
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1370 
1380 
1390 
1400 
1410 
1420 
1430 
1440 
1500 
1510 
1520 
1530 
1540 
1550 
1560 
1570 
1580 
1590 
1600 
1610 
1620 
1630 
1640 
1650 
1660 
1670 
1680 
1690 
1700 
1710 
1720 
1730 
1740 
11750 
760 
1770 
1780 
1790 
1800 
1810 
1820 
1830 
1840 
1850 
1860 
1870 
1880 
1890 
1900 
10000 


KD = 201/64 
REM C2 
KE = .967653590E - 3 


REM R1,R2,R3,R4,R5. 
DIM KK(5) 
KK(0) = - .166666666:KK(1) = .833333072E - 2 
KK(2) = - .198408328E - 3:KK(3) = .275239711E - 5 
KK(4) = - .238683464E - 7 
REM ***TAN/COTAN**« 
REM YMAX 
KG = INT (2 A 16 + 3.14159265 / 2) 
REM 2/P| 
KH = .636619772 
REM C1 
KI = 201 / 128 
REM C2 
KJ = .000483826795 
REM EPSI 
KL = .85E38 
REM ***ATAN/ATAN2*«« 
REM 2-SQR(3) 
KM = .267949192 
REM SQR(3) 
KN = 1.7320508 
KP = 3.14159265 
REM AO,A1,A2,A3 
DIM KQ(4) 
KQ(0) = 0:KQ(1) = .523598776 
KQ(2) = 1.57079632:KQ(3) = 1.04719755 
REM P1 
KR = - .720026849 
REM PO 
KS = - 1.4400834 
REM Q1 
KT = 4.75222585 
REM Qo 
KU = 4.3202504 
REM xx TAN «x« 
REM P1 
KV = - 111361440 
REM P2 
KW = .00107515474 
REM Qo 
KX =1, 
REM Q1 
KY = - 444694772 
REM Q2 
KZ = .0159733921 
STOP 
REM «TR = SIN(TX)+* 
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10010 
10020 
10030 
10040 
10050 
10060 
10070 
10080 
10090 
10100 
10110 
10120 


10130 
10140 
10150 
11000 
11010 
11020 
11030 
11040 
11050 
11060 
11070 
11080 
11100 
11110 


11120 
11130 
11140 
11150 
11160 
11170 
11180 
12000 
12010 
12020 
12030 
12040 
12050 
12060 
12070 
12080 
12090 
12100 
12110 
12120 
12130 
12140 


TY = ABS (TX):TS = SGN (TX): GOTO 10050 

REM ***TR=COS(TX) + 
TY = ABS (TX) + KA:TS = 1: GOTO 10050 

REM COMMON TO SIN & COS 

IF TY > = KB THEN PRINT “SIN/COS”:FC$: STOP 
TN = INT (TY*KC + 55) 
TT = .5 «TN: IF TT > INT (1T) THEN TS = -TS 

IF ABS (TX) < > TY THEN TN = TN-.5 
TF = ( ABS (TX) - TN« KD) - TN» KE 

IF ABS (TF) < KF THEN TR = TF: GOTO 10130 
TR = TF*TF 
TR = ((((KK(4) * TR + KK(3)) * TR + KK(2)) «D> 
TR + KK(t)) * TR + KK(0)) * TR 
TR=TF+TF+TR 

IF TS <0 THENTR = -TR 

RETURN 

REM ***TR = TAN(TX)=** 

GOSUB 11100 

IF TN = INT (TN) THEN TR = TS/ TT: RETURN 
TR = - TT/TS: RETURN 

REM **TR =COTAN(TX)««« 

IF ABS (TX) > KL THEN PRINT “COTAN”:FC$: STOP 

GOSUB 11100 

IF TN = INT (TN) THEN TR = TT/ TS: RETURN 
TR = - TS/ TT: RETURN 

REM COMMON TO TAN & COTAN. 

IF ABS (TX) > KG THEN PRINT “TAN/COTAN”:> 

FC$: STOP 
TN = INT (TX « KH + .5) 
TF = (TX- TN*Kl)- TN« KJ 

IF ABS (TF) < KF THEN TS = TE-TT = 1:GOTO 11180 
TT = TF+ TF 
TS = (KW*+ TT + KV)* 71+ TF + TF 
TT = (KZ» TT + KY) * TT + KX 
TN = 5» TN: RETURN 

REM *«TR = ATAN(TX)**« 
TF = ABS (TX): GOSUB 12200 

IF TX <0 THENTR = -TR 

RETURN 

REM ***TR = ATAN2(TU,TV)««« 

IF TU < > 0 GOTO 12080 

IF TV = 0 THEN PRINT “ATAN2”:FC$: STOP 
TR = KA: GOTO 12130 
TN = TV: GOSUB 12310:TF = TN 
TN = TU: GOSUB 12310 

IF TF - TN > 126 THEN TR = KA: GOTO 12120 
TF = ABS (TV/ TU) 

IF TF = 0 THEN TR = 0: GOTO 12140 

GOSUB 12200 

IF TU <0 THEN TR = KP-TR 
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12150 
12160 
12200 
12210 
12220 
12230 


12240 
12250 
12260 
12270 
12280 
12290 
12300 


12310 
12320 


IF TV <OTHENTR = -TR 
RETURN 
REM COMMON TO ATAN & ATAN2. IN= TF OUT=TR. 
™ =0 
IF TE > 1 THEN TF = 1/TETN = 2 
\F TF > KM THEN TF ((TF « KN) - 1)/(KN + TF):TN => 
TN 44 
IF ABS (TF) < KF THEN TR = TF: GOTO 12280 
TY = TF*TF 
TY = ((TY*KR + KS) 
TR = TF + TF*TY 
IF TN >1THENTR =-TR 
TR = KQ(TN) + TR: RETURN 
REM TN=EXP. OF MOST RECENTLY REFERENCED 
VARIABLE 
TN = PEEK ( PEEK (133) + 256 » PEEK (134)) 
RETURN 


1a dl 


TY) / (TY + KT) * TY + KU) 
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CHAPTER 3: OPERATORS 


NUMERIC OPERATORS 


Operators are listed in descending order of priority, i.e., the 
operators with the smallest “priority” numbers have the 


highest priority. 








Numeric Operators 








oper- pri- 
ator  ority function example of use 
0) 0 overrides other A=5*(4+3) 
priority rules 
- 1 negation A=-822 
a 2 exponentiation A=24 3 
* 3 multiplication A=2°6 
/ 3. division A=8/2 
+ 4 addition A=8+1 
- 4 subtraction A=8-1 
= 5 is equal to IF 5=0 GOTO 90 
<> 5 is not equal to FL=5<>0 
< 5 is less than 
<= 5 is less than or equal to 
> 5 is greater than 
>= 5 is greater than or equal to 
NOT 6 _ logical “not” IF NOT 6=5 GOTO 90 
A=NOTHI 
AND 7 __ logical “and"!"! IF 1 AND 0 GOTO 90 
A=1 AND 1 
OR 8 logical “or! IF 1OR 0 GOTO 90 
A=00R0 


result 


no action 
FL=-1 


go to 90 
A=0 


no action 
A=1 


goes to 90 


"3. Logical operators act on integer values rather than numeric 
values. Integer values must be in the range -32768 to +32767.A 


value out of this range causes an FC error. 
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. a5 
« 9 
2 .s 
STRING OPERATORS G . CHAPTER 4: RESERVED WORDS 
6 
¢ 2 
String Operators > a ABS \F REM 
© 3 AND INPUT RESTORE 
oper. pri- 4 ASC INT RETURN 
ator ority’#! Function example of use result od a ATTACH LEFT$ RIGHTS 
LEN RND 
e 2 BYE 
CALL LET RUN 
ides oth . @ 
Pes orony les? © 2 CHR$ LIST SGN 
+ 4 concatenation AS='8'+'1' A$ ='81" e 4 CLEAR LOG SQR 
= 5 is equal to . acess oe 90 he action e = CONT MID$ ier 
<> 5 i t It L='XX'<>'X’ L=-1 
< 68 islesstran e ? DATA NEW 2 
<= 8 is less than or equalto >) DEF NEXT STOP 
> 5 is greater than Se R 
>=  § is greater than or equal to * DIM NOT STR$ 
e END ON TAB 
e °? EXP OR THEN 
Where Basic must disregard the order of precedence to e 4 FN PEEK TO 
avoid a TM error (type mismatch), it does so automatically. FY FOR POKE TROFF 
Here is an example of such a situation: el FRE POS TRON 
3 
Fae aed i eet e 4 GET PRINT VAL 
The normal order of precedence would evaluate A+ X$’ first. e | j GOSUB ? 
That would produce a type mismatch, however, so Basic e | 3 GOTO READ 
evaluates ‘X$=Y$’ first, yielding a 0 or -1, which may be | 2 
added to A. . A | 
e bo 
|? 
el? 
ar 
| 4 
e | 2 
ed 
© | 9 
2). There are no situations in Microsoft Basic where parentheses | 4 
may be used to alter the order of precedence in a string expression; © [ 
however, parentheses are valid in such expressions. PA l Ss 
| o 44 
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CHAPTER 5: LINE NUMBERS, 
NUMBERS, AND STRINGS 


LINES 

Maximum length: 80 characters (after Basic has edited a 
line into storable form) 

Minumum value: 0 

Maximum value: 63999 


Values allowed: any integer value from minimum to max- 
imum. 


NUMERIC VALUES 


Maximum/minimum value: approximately +1.70141+10°8 
Tiniest nonzero value: approximately +2.93874*10 °° 
Maximum precision: approximately 9 decimal digits 


INTEGER VALUES 


The limits on integer values apply only to the values of 
integer variables. A numeric variable may have an “integer 
value” (a value that contains no decimal part) in the range 
+999,999,999. 


Maximum value: 32767 
Minimum value: -32768 


RULES FOR DISPLAYING NUMERIC VALUES 
(PRINT AND STR$) 


1. If a number is negative, the first character displayed is ‘-’. 
Otherwise the first character displayed is “space.” 


The number follows. It contains only as many digits as are 
needed to represent it completely. There are no jeading 
zeroes before the decimal point (if any), and no trailing 
zeroes after the decimal point (if any). 


The number is not divided by commas into groups of 
three characters, although such commas are used in 
some parts of this book to make large numbers more 
readable. 
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2. If the number is an integer (with no decimal part) in the 
range +999,999,999, it is displayed as an integer, with no 
decimal point. 


Examples: -32 0 325000 


3. If the absolute value of the number is in the range .01 <= 
n < 1,000,000,000 the number is displayed as a real 
value (with a decimal point). 


Examples: 1 -.4 
9111.11111 


3.141592 
-9111.11111 


4. If the number doesn't fit into category (2) or (3) above, itis 
displayed in scientific notation. 


The mantissa is expressed as a number in the range 
1<=n<10. If it can be expressed as an integer in that 
range, it is displayed as an integer. Otherwise it is 
displayed as a real number. 


Examples: 3E+14 3.14E +14 

‘Eis followed by a sign, ‘+’ or ‘-’, and a two-digit 
exponent. 

Examples: 3.14E +14 3E - 03 


RULES FOR READING NUMERIC VALUES 
(INPUT AND VAL) 


The rules for reading numeric values are essentially the 
same as the rules for displaying them, except that the rules 
that choose between alternate forms of a number do not 
apply. For example, any number, regardless of value, may 
be input in scientific notation, or as a decimal value, or (value 
permitting) as a integer. 


1. If anumber is negative, the sign must be ‘-’. Otherwise the 
sign may be ‘+’ or may de absent. Leading blanks are not 
allowed. 


2. After the sign, if any, is an integer constant or numeric 
constant. 


Basic considers the number to stop at the first character 
that is not part of a valid value. For example, if the value 
being read is ‘50,000’, Basic reads ‘50’. If the number is 
‘50’ (with a leading blank), Basic reads ‘0’, since leading 
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blanks are not allowed. 


If the number is in floating point notation, it ends here. If the 
number is in scientific notation, the following parts must be 
present. 


3. The next character is ‘E’ (it must be in upper case). 


4. Next is the exponents sign. If the exponent is negative, its 
sign is ‘-’. Otherwise its sign may be ‘+’, or may be 
absent. 


5. Next is the exponent, which must be an integer. 


6. The entire number must be within the valid range of a 
numeric variable. 


For example, all of the following numbers are valid and 
equivalent: 


3.14E +14 3.14E14 3.14E + 0000014 
314E+12 314000E9 +0.314E4+15 
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CHAPTER 6: BASIC PROGRAM 
EDITOR QUICK REFERENCE 


ADDING, DELETING, REPLACING, OR 
COPYING A LINE 


Change To Be Made Procedure 





Add a line 


Delete a line 


Replace a line 


Copy a line 


Type a line with a line number before it. 
Basic inserts the line in the program in 
line number order. 


(1) Type a line number alone: press 
ENTER. 


or 


(2) LIST a line and delete everything 
except the line number, then press ENTER 
to make Basic accept the edited line. 


Type a new line with the same line number 
as the line you want to replace. 


or 


LIST a line and type over everything 
except the line number. 


LIST a line and change its line number to 
the line number you want the copy to 
have. Press ENTER to make Basic accept 
the edited line. 


CURSOR MOTION 


Editing Operation Keystrokes 
. Move cursor left 4 
Move cursor right » 
Move cursor left to end of line LOCK 4 
Move cursor right to end of line LOCK » 
6-1 








INSERT CHARACTERS 


Editing Operation 
Insert a character, x 


Insert multiple characters 


Insert a space; move cursor right 
Insert a space; don't move cursor 


Insert multiple spaces; 
move cursor right 


Insert multiple spaces; 
don’t move cursor 


Insert spaces continuously; 
move cursor right 


Insert spaces continuously: 
don’t move cursor 


DELETE CHARACTERS 


Editing Operation 


Delete character under cursor; 
don't move cursor 


Delete character under cursor; 
move cursor left 


Delete characters from cursor 
right; don't move cursor 


Delete characters from cursor 
left; move cursor left 


Delete characters from cursor 
to end of line 


Delete characters from cursor 
to start of line 


SHORTCUTS 


Editing Operation 

Review a line longer than LCD 

Go directly from any INSERT mode 
to any DELETE mode 


Go directly from any DELETE mode 
to any INSERT mode 


Interrupt a ‘LOCK’ operation 
before its natural end 


Keystrokes 
INSERT x 


LOCK INSERT xxxxx... 
Press INSERT again when done. 


INSERT 6 
INSERT 4 


LOCK INSERT pop. . . 
Press INSERT again when done. 


LOCK INSERT 4¢¢. . . 
Press INSERT again when done. 


LOCK INSERT LOCK » 
Press INSERT again when done. 


LOCK INSERT LOCK ¢ 
Press INSERT again when done. 


Keystrokes 


DELETE » 
DELETE ¢ 
LOCK DELETE oop. . . 


Press DELETE again when done. 


LOCK DELETE 4¢4@... 
Press DELETE again when done. 


LOCK DELETE LOCK » 
Press DELETE again when done. 


LOCK DELETE LOCK ¢ 
Press DELETE again when done. 


Keystrokes 


ROTATE 
Press ROTATE again when done. 


Skip pressing INSERT. 


Press DELETE, LOCK DELETE, etc. 


Skip pressing DELETE. 
Press INSERT, LOCK INSERT, etc. 


Press any key. 
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CHAPTER 7: PERIPHERAL 
DEVICES 


CONTROL CHARACTERS 


Control characters are “characters” which do not generate 
output on an output device, but cause the device to perform 
control functions, such as cursor movement. 


There are three categories of contro! characters for you to be 
concerned with: 


1. ASCII standard control characters which are recognized 
by the HHC. These characters are listed in the following 
table with numeric values below 32. 


2. ASCII standard contro! characters which are not recog- 
nized by the HHC. These are all the characters repre- 
sented by numeric codes below 32 that are not listed in 
the following table. 

3. HHC control characters that are not standard ASCII 
control characters. These are characters listed in the 
following table with numeric values above 32. 


lf you write a control character to a device that does not use 
it, the device will either ignore the character or display its 
HHC graphic representation. See the descriptions of indi- 
vidual devices for details. 


ASCII Control Characters 


numeric ASCII 
value name std typical meaning 





7 bell yes Sounds audible alarm. 
8 backspace yes Move cursor left one position; erase 
character cursor is moved to. 

10 line feed yes Move cursor down one line. 

12 form feed yes Move cursor to start of first line on next 
page. 

13 carriage rtn yes Move cursor to start of next line. (Note 
that “carriage return” does an automatic 
line feed on HHC peripherals. This 
differs from its action on some other 
devices.) 

27 escape yes Marks beginning of an escape control 
sequence. 

128 cursorup no Moves cursor up one line. 
129 cursor left no Moves cursor left one character; does not 


erase character cursor is moved to. 
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numeric ASCII 
value name std_ typical meaning 





130 Cursor right no Moves cursor right one character: does not 


replace character under cursor with a 
blank. 


131 cursor down no Moves cursor down one line (equivalent to 


line feed). 


ESCAPE CONTROL SEQUENCES 


Escape control sequences provide an extended set of 
control characters on the HHC. Each sequence is 3 bytes 
long: 


byte meaning 
0 escape (ASCII value 27) begins an escape 
control sequence. 
1 operation code (opcode). 


data; meaning depends on the opcode. Unless 


noted other wise below, the data byte is ignored. 


The HHC has a standard set of escape control sequences 
which apply to all peripherals. Not all peripherals respond to 
all escape control sequences, however. If a peripheral does 
not respond to a particular escape control sequence, it 
ignores that sequence; that is, the sequence is a “no- 
operation” command for that peripheral. 


In some other HHC manuals the opcodes are referred to by 
five-character symbols. These symbols are included in the 
following table. 


Opcodes 


Name: LCD Unescape 
Opcode: 64 
Symbol: ESCUN 


On the LCD, the data byte is displayed (as in ESCDA). On all 
other devices, it is ignored. 


Name: Insert Right 
Opcode: 65 
Symbol: ESCIR 


The data byte is displayed at the cursor. The character pre- 
viously under the cursor, and all following characters on the 
line, are pushed to the right. 
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Name: Delete Right 
Opcode: 66 
Symbol: ESCDR 


The character under the cursor is deleted; following charac- 
ters on the line are moved left. The data byte is used as a fill 
character at the end of the line. 


Name: Set Inverse Mode 
Opcode: 67 
Symbol: ESCSI 


Subsequent output is displayed in inverse-image (the colors 
of the character and background are reversed). 


Name: Set Uninverse Mode 
Opcode: 68 
Symbol: ESCUI 


Subsequent output is displayed normally (not inverse- 
image). Reverses the effect of ESCSI. 


Name: Set Flash Mode 
Opcode: 69 
Symbol: ESCSF 


Subsequent output will be displayed in flashing characters. 


Note: the advent of flashing may be delayed (i.e., characters 
written immediately after “set flash mode” may not flash) 
under some circumstances. You can force flashing to begin 
* by doing an I/O operation on any device other than the LCD. 


Name: Set Unflash Mode 
Opcode: 70 
Symbol: ESCUN 


All subsequent output is displayed in non-flashing charac- 
ters, until the mode is changed by ESCSF. Reverses the 
effect of ESCSF 


Note: the end of flashing may be delayed, like the advent of 
flashing (see above). 


Name: Display Character Absolute 
Opcode: 71 
Symbol: ESCDC 


The data character is displayed, even if it is a control 
character that would normally be executed. For example, if 
the next data character is 13 (carriage return) and it is sent to 
the micro printer, it is written as an inverse-imageM. 


Name: Fiush |/O Buffer 
Opcode: 72 
Symbol: ESCFL 


Characters in the device’s 1/O buffer are written (if they are 
being output) or discarded (if they are being input), emptying 
the buffer. 


This operation is generally applied only to output devices 
that write a line of data at a time. Writing a line would 
normally be triggered by a CR character. 


Name: Set Control Character Mode 
Opcode: 73 
Symbol: ESCCC 


If the data byte is non-zero, subsequent non-executable con- 
trol characters sent to the device will be displayed: if zero, 
subsequent non-executable control characters sent to the 
device will not be displayed. 


Name: Home Cursor 
Opcode: 74 
Symbol: ESCHM 


Returns the cursor to the upper left corner of the display. 


Name: Set Word Break 
Opcode: 75 
Symbol: ESCWB 


The data byte defines the word break character. When the 
device encounters this character in output data, it considers 
the character to mark the break between two words. 


When an output line becomes longer than the device's 
maximum line length, the device word-wraps automatically; 
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that is, it ends the line and moves the last word of the line 
down to the next line, so that the word will not straddle a line 
break. 


The initial value of the word break character is 32 (space) for 
each device. 


If you set a device’s word break character to 255, word 
wrapping is disabled for that device. 


Note that the LCD has no word-wrap capability. 


THE KEYBOARD 


The keyboard is normally attached to LUN #0. Unlike 
peripherals, it has no device code. Thus it cannot be 
attached to another LUN with the ATTACH statement. You 
can attach it to a device with a POKE into the SDT. This 
POKE and warnings about its use are described in Chapter 8. 


Technical Information 
ATTACH device code: none; see note above. 
Control codes: not applicable to input-only devices. 


Escape control sequences: not applicable to input-only 
devices. 


THE LCD 


The LCD is normally attached to LUN #1. Like the keyboard, 
it has no device code. Thus it cannot be attached to another 
LUN with the ATTACH statement. You can attach it to a 
device with a POKE into the SDT. This POKE is described in 
Chapter 8. 


Technical Information 
ATTACH device code: none. See note above. 


Control codes: 


Code Meaning Function on device 


7 Bell Makes the HHC beep. 


8 Backspace Backspaces the cursor, erasing the character the 


cursor was previously at.'"’ 
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Code Meaning Function on device 
12 Form feed A no-operation on the LCD. 
13 Carriage rtn Clears display and moves cursor to left 
edge of LCD. 
27 Escape Begins an escape control sequence. 
129 Cursor left Non-destructive backspace.'"! 
130 Cursor right Non-destructive space. 


Escape control sequences: the LCD supports al! of the 
standard escape control sequences except ESCFL, ESCCC 
and ESCWB. Note that the data byte of ESCUN is displayed 
on the LCD (as in ESCDC); it is ignored on all other devices. 


THE TV ADAPTOR 


The TV adaptor may be coupled to a standard black-and- 
white or color television receiver or video monitor. It provides 
a two-dimensional display that is more useful for many 
purposes than the one-line display on the HHC’s LCD. 


The TV Adaptor display shows 16 lines, each 32 characters 
long. It can also generate several kinds of dot-matrix graphic 
displays. On a color television set, it can display letters, 
graphics, and background in various colors. 


Technical Information 
ATTACH device code: 67 (output) 
Control codes and escape control sequences: 


The TV Adaptor has many control codes and escape control 
sequences, and a description of them would be much too 
long to include in this manual. Information on programming 
for the TV Adaptor may be found in another publication. 


THE MICRO PRINTER 


The micro printer prints 15-column lines on a roll of paper 
1.4” wide. It has a “thermal” printing mechanism that makes 
marks on specially coated paper by heating tiny areas in the 
print head. 


The micro printer uses a buffer in the HHC’s RAM that can 
hold up to two lines of data. The printer accumulates two 
lines at a time, and prints them in a single operation. 





om - if the cursor is in the leftmost character position, the backspace 
will shift all existing characters to the right and insert a blank space in 
the first character position. 
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Technical Information 
ATTACH device code: 68 
Control codes: 


Code Meaning Function on device 
7 Bell No-operation. 
8 Backspace “Erases” the last character sent to the 


printer, if it has not already been 
printed. Several backspaces in a row will 
erase several characters. 


10 Line feed No-operation. The micro printer 
automatically advances the paper when it 
does a carriage return. A separate line 
feed operation is not supported. 


12 Form feed Ends the current line of output, prints the 
contents of the printer’s buffer, and 
advances the paper 4 lines. 


13 Carriage rtn Ends and prints the current line of output. 
If the buffer contains two lines of output, it 


prints both. 
27 Escape Begins an escape control sequence. 
81 Cursor left Non-destructive backspace. 


82 Cursor right Non-destructive space. 


Escape control sequences: ESCCC, ESCDC, ESCDR, 
ESCFL, ESCHM, ESCIR, ESCUN, and ESCWB. 


SERIAL INTERFACE ADAPTOR 


The serial interface adaptor enables the HHC to do I/O ona 
great variety of devices designed to communicate through 
an RS232C interface. This interface, established by the 
Institute of Electrical and Electronic Engineers (IEEE), is 
widely used for low- and medium-speed peripheral devices. 


Initializing the Serial Interface 


Befcre you use the serial interface for the first time, you may 
need to use the interface program’s configuration option to 
make the interface compatible with the device you want it to 
control. The configuration program sets properties such as 
the type of error checking the serial interface is to do. 


To configure the serial interface, plug the interface into the 
HHC. and turn it on with the I/O menu; select the “Serial I/O” 
program from the primary menu, and then select the “Confi- 
gure” option from the program’s menu. 
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The configuration program creates an “invisible” file which 
contains initialization data'?? Whenever you use the serial 
interface, the HHC automatically reads this file and initializes 
the serial interface from the information contained in it. Thus, 
you need not run the interface’s configuration program again 
unless the initialization file is somehow deleted. 


The initialization file can contain a separate set of data for 
the bus socket on the HHC (slot #0 in the /O key menu) and 
for each socket in the I/O adaptor (slots #1 through #6 in the 
menu). Thus, you can set up the initialization file so that you 
can change the interface’s configuration just by plugging it 
into a different slot. 


if you have some computer experience, you will probably 
find the configuration program to be self-explanatory. If you 
do not, see the manual that accompanies the serial inter- 
face’s program capsule for instructions. 


It is possible to initialize the serial interface from a Basic 
program, but the process requires some understanding of 
the HHC’s machine language, and is beyond the scope of 
this manual. 


Note About Protocols 


The serial interface’s configuration program can make the 
serial interface operate with or without a transmission 
protocol. This is a set of rules that a computer and a 
peripheral (or two computers) can use to make sure that 
neither one sends characters when the other is unable to 
receive them. 


Whether or not you initialize the serial interface for a 
transmission protocol must depend on whether the interface 
is connected to a device that uses one. Unless the serial 
interface and the device connected to it are using the same 
protocol, they cannot communicate properly. 


The serial interface supports two alternate software pro- 
tocols: XON/XOFF protocol and ETX/ACK protocol. If neith- 
er is used, the Data Terminal Ready (DTR) line in the data 
transmission cable controls communication. 


XON/XOFF protocol is commonly used in communications 
between the HHC and another computer. Many kinds of 
printers and other peripheral devices use it as well. 


Suppose you are using XON/XOFF protocol to communicate 
between the serial interface adaptor and a printer. Here is 
how the protocol works. 





eh. an invisible file is one that does not appear in the file system 
editor's menu or in Basic’s menu. 
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As the printer receives characters from the serial interface, it 
stores them in a buffer until it can print them. If the serial 
interface sends characters to the printer faster than the 
printer can print them, the printer’s buffer eventually fills up. 
When the buffer is almost full, the printer sends the interface 
an XOFF command (‘transmission off,’ ASCII code #19). 
This makes the interface stop transmitting. When the prin- 
ter’s buffer becomes less full, the printer sends an XON 
command (‘‘transmission on,” ASCII code #17). This makes 
the interface resume transmitting. 


XON/XOFF protocol works for input to the HHC, as well as 
output from it. Suppose you were using the serial interface to 
communicate with another computer, which could both send 
and receive characters. \f the other computer sends charac- 
ters faster than the HHC can process them, eventually the 
serial interface’s buffer fills up. Then the serial interface 
sends an XOFF command to make the other computer stop 
transmitting. Later the serial interface sends an XON com- 
mand to make the other computer resume transmitting. 


XON/XOFF protocol has two effects on you as a user of the 

serial interface: 

1. You do not have to worry that the device attached to the 
interface might lose data because the HHC continued 
transmitting when the device’s buffer was full. The serial 
interface handles the XON/XOFF protocol automatically, 
and prevents any such mishap from occurring. 

2. You cannot transmit or receive the ASCII codes #17 
(XON) and #19 (XOFF) as data characters (excepi as 
part of an escape control sequence). If you try, the device 
connected to the serial interface will interpret the charac- 
ters as XON and XOFF commands. That will make it start 
or stop transmitting data at inappropriate times. 


ETX/ACK protocol is commonly used by peripheral devices 
such as printers. Its purpose is the same as the purpose of 
XON/XOFF protocol: to make sure that the serial interface 
does not send information when the attached device is 
unable to receive it. 


In ETX/ACK protocol, the serial interface transmits a string 
of characters, called a message, that is known to be short 
enough for the device to process without losing characters. 
The interface ends the message with an ETX character 
(“end transmission,” ASCli code #3). When the device has 
processed the message and is ready for another one, it 
sends an ACK character (“acknowledge,” ASCII code #6). 
This signals the serial interface that it may send another 
message. 


Unlike XON/XOFF, ETX/ACK protocol works only for trans- 
missions in one direction: from the Serial Interface Adaptor 
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to a device. Thus it is unsuitable for devices that engage in 
two-way communication, such as modems and keyboard 
printers. 


The effects of ETX/ACK protocol on you as a user are the 
same as the effects of XON/XOFF protocol, except that the 
ASCII character you cannot transmit as data (except as part 
of an escape control sequence) is #3 (ETX) instead of #17 
(XON) and #19 (XOFF). (You can transmit ACK as a data 
character, since it has a special meaning only when re- 
ceived by the Serial Interface.) 


Technical Information 
ATTACH device codes: 70 (output) and 134 (input) 


Control codes: none; but see the discussion of transmis- 
sion protocols, above. 


Escape control sequences: none. The “escape” control 
character (ASCII code 27) is treated as data. 


THE MODEM 


The modem enables you to communicate with other compu- 
ters via telephone. Two rubber cups on the modem hold the 
mouthpiece and earpiece of a standard telephone handset. 


The modem encodes the information that the HHC writes to 
it in sound patterns and transmits them over the telephone. It 
receives information in the same fashion, and passes it to 
the HHC when the HHC “reads” the modem. 


The modem contains an object called a control ROM, which 
is similar to an HHC capsule, but contains a program to 
control the operation of the modem itself, as well as an 
application program that you can run from the primary menu. 


The modem’s control ROM is interchangeable in much the 
same way that an HHC capsule is. Two control ROMs are 
available for the modem at this time; their names are 
Telecomputing | and Telecomputing 2. Their functions are 
similar, but Telecomputing 2 has more features than 
Telecomputing | does. For details on the features of these 
programs, study the instructions that accompany the mod- 
em, and speak to the distributor of your HHC. 
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Initializing the Modem 


Before you use the modem for the first time, you may need 
to use the telecomputing system’s configuration selection to 
make the modem compatible with the computer you want 
the modem to communicate with. The procedure for con- 
figuring the modem is very similar io the procedure for 
configuring the serial interface adaptor, described above. 
The major differences are: 


1. The modem’s configuration file can hold only one set of 
configuration data, rather than one set per I/O slot, as the 
serial interface’s configuration file does. 

2. The modem supports XON/XOFF protocol, but does not 
support ETX/ACK protocol. (Telecomputing | sends XON/ 
XOFF to the host computer, but does not “listen” for 
them. Telecomputing 2 can send and listen for XON/ 
XOFF) 


Technical Information 


ATTACH device code: 130 (input) and 66 (output) 


Control codes: none; but see the notes on XON/XOFF 
protocol above, and under the description of the serial 
interface adaptor. 


Escape control sequences: none. The “escape” control 
character (ASCII code 27) is treated as data. 
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CHAPTER 8: PEEKS AND POKES 


INPUT AND OUTPUT 


The System Device Table (SDT) 


The HHC keeps track of LUN attachments through the 
System Device Tabie (SDT). The SDT is kept at locations 
705 through 712. 


The byte at: represents LUN: 
705 #0 (normally the keyboard) 


706 #1 (normally the LCD) 
707s #2 
708 83 #3 
709 «#4 
710 «#5 
711 #6 
712 #7 
713 «#8 
714. «#9 
715 «#10 
716 #11 
717s #12 
718 #13 
719 «#14 
720» «#15 


Interpret the value of each byte as follows: 


value means 
0 Keyboard is attached to this LUN. 
6 LCD is attached to this LUN 

255 Nothing is attached to this LUN. 


other A peripheral is attached to this LUN. 
Values indicate the order in which 
peripherals were ATTACHed, not 
peripherals’ device types. 


To unattach a device, POKE 255 into the proper SDT entry. 


To attach the keyboard or LCD to a LUN, POKE 0 or G into 
the proper SDT entry. (The ATTACH statement does not 
work for these devices, since they have no device codes.) 


Note: never leave a device attached to more than one LUN 
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at a time! If you do so, your program may behave unpredict- 
ably. 


Treat LUNs #0 and #1 very carefully, since they are your 
channels for communicating with the HHC. If your program 
should leave LUN #0 without a properly attached device, 
you will be unable to control the HHC; if it leaves LUN #1 
without a properly attached device, you will be unable to see 
what you are doing. Either way, you may have to press 
CLEAR to reset the device attachments. 


Note: do not press any key on the HHC’s keyboard when 
LUN #0 is attached to a peripheral device. lf you do so, 
the HHC may “freeze up” and execute only one Basic 
statement each time you press a keyboard key. If this 
happens, the HHC will remain “frozen” until you return to the 
menu or reattach LUN #0 to the keyboard. 


Note: do not “type ahead” with the HHC keyboard or any 
peripheral attached to LUN #0. 


The ATTACH Statement 


The ATTACH statement does not give error messages, even 
when it fails. In the normal course of things, your first 
indication of an unsuccessful ATTACH is an IO error when 
you try to do an INPUT, GET, or PRINT. 


To determine whether the most recent ATTACH suc- 
ceeded, PEEK at location 926: 


value means 
0 most recent ATTACH failed, or no ATTACH 
done yet. 
1 most recent ATTACH succeeded 


THE HELP AND I/O KEYS 


To make the HELP and/or I/O keys function while you are 
in Basic, POKE the following values into location 524: 


value means 
OQ HELP and |/O both function 


1 HELP functions 
4 W/O functions 


5 neither key functions (the normal case) 
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Note: if you have used the POKE to activate the HELP 
function, your setting in location 524 may change after the 
HELP key is actually pressed. 


Note: while you are in Basic, the |/O key may only be used to 
determine how much free space remains in a memory area 
other than the current memory area, and to determine 
whether a peripheral is on or off. 


To determine how much free space remains in the current 
memory area, use the FRE function. To turn a peripheral on 
or off, return to the Basic menu or the primary menu before 
using the 1/O key. 


THE KEYBOARD BUFFER 


The HHC stores keystrokes that it has not yet processed ina 
keyboard buffer. You can use PEEK to look ahead at the 
contents of this buffer before you do an INPUT or GET, and 
you can use POKE io “type” into the buffer, so that your 
program, in effect, is pressing keys on the keyboard. 


Note: you must be very careful because one character can be 
removed from the buffer for each Basic instruction executed. 


Structure Of the Keyboard Buffer 


The keyboard buffer is 8 bytes long. The bytes in the buffer 
are numbered 0 to 7. The HHC places the first character 
typed in the 7th byte, the second in the 6th byte, etc. After 
the 8th character typed has been placed in the Oth byte, the 
9th character typed is placed in the 7th byte (assumingthe 
1st character typed has been read by the program), and so 
on. 


The HHC maintains two pointers to the keyboard buffer. A 
“store” pointer contains the number (0 to 7) of the byte 
where the next character typed on the keyboard will be 
stored. A “fetch” pointer contains the number of the byte 
where the next character read by the program will come 
from. 


For example, suppose you have just entered Basic and 
nothing has been typed yet.'"! The keyboard buffer and its 
pointers look like this: 


ee a keyboard buffer 
“store” pointer 
t “fetch” pointer 


‘ . This is an oversimplification, since the same buffer is used by 
the rest of the HHC. Something had to have been typed for you to 
have entered Basic from the primary menu. The discussion of the 
process is accurate, however. 
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Now suppose you type in 3 characters, ABC’. Your program 
does a GET, so that you have input 3 characters, and your 
program has read one. Now the buffer looks like this: 


t “store” pointer 
t “fetch” pointer 


You continue typing in the alphabet, and your program 
continues GETing characters. At some later time when you 
have typed the alphabet through J and your program has 
read it through E, the buffer looks like this: 


t “store” pointer 
t “fetch” pointer 


The Pushkey Buffer 


The HHC has a second buffer called a pushkey buffer 
which it uses to hold characters that are “pushed” back into 
the input stream by a program. 


Whenever Basic does an INPUT or GET, the HHC returns 
any characters that are in the pushkey buffer before going to 
the keyboard buffer. Thus, any characters you store in the 
pushkey buffer will be read before characters typed in 
through the keyboard, even if the keyboard characters go 
into their buffer first. 


The pushkey buffer is 4 characters long. It is used as a LIFO 
queue (the last character put in is the first taken out). The 
“bottom” of the buffer, where the first character is pushed, is 
character 0; the “top,” where the last character may be 
pushed, is character 3. 


A pushkey counter indicates the number of characters 
already in the buffer. Its value may be 0 to 4. A value of 0 
means the pushkey buffer is empty; 4 means the pushkey 
buffer is full, and there is no more space for characters to be 
pushed into it. 


For example, if you push a ‘2’, then a ‘G’ into the buffer, the 
buffer looks like this: 


2G______ pushkey buffer 


pushkey counter = 2 
INPUT or GET will receive the ‘G’, then the ‘2’: 


_2______ pushkey buffer 
pushkey counter 


Il 
—_ 


———— pushkey buffer 
pushkey counter = 0 (empty) 
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Buffer Locations 
location contains 

620 keyboard buffer (location of character 0) 

518 “store” pointer to keyboard buffer 

519 “fetch” pointer to Keyboard buffer 

628 pushkey buffer (location of character 0) 


522 pushkey pointer 


PEEKs and POKEs 


To inspect the pushkey buffer, PEEK at the pushkey 
pointer. If it is O, the pushkey buffer is empty. If it is not zero, 
use it to extract the contents of the pushkey buffer. 


The following subroutine assembles a string whose value is 
the current contents of the pushkey buffer: 


ae a > 





t 


To POKE a character into the pushkey buffer, check to 
make sure it is not full. It it is not, POKE the character into 
the buffer position indicated by the pushkey counter, then 
increment the counter. 


To POKE a character into the “top” of the keyboard 
buffer, so that it will be the next character to come out: first, 
check to make sure that the buffer is not full. Then move the 
“fetch” pointer backwards one location, and POKE the 
character to the location the “fetch” pointer now indicates. 


Do not try to put a character into the “bottom” of the 
keyboard buffer by POKEing into tne location indicated by 
the “store” pointer and advancing the pointer. If you do this, 
there is always a risk that you will POKE a character at the 
same time that the real keyboard inputs a character; if this 
happens, one character or the other will be lost. 
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FUNCTION KEYS 


The definitions of the three function keys are kept in three 
consecutive areas, each 16 bytes long. Each area begins 
with a byte containing the length of a function key definition 
in characters, followed by 15 bytes containing the definition. 
If the definition is less than 15 characters long, the part of the 
area beyond the end of the definition is ignored. 


The locations that contain the function key definitions are: 


location contents 
642 Length of f1's definition. 
643 f1's definition. 
658 Length of f2's definition. 
659 f2's definition. 
674 Length of 3's definition. 
675 13's definition. 


You can change the definition of a function key by POKEing 


appropriate values into the that function key’s definition 
area. 


“Typing” a Function Key 


You can “type” a function key by POKEing it into the 
keyboard buffer, but the preferred way to do it is to do the 
two POKEs described below. 


ra FA=642, the location of the length of F1's definition: 
en: 





to “type” a 
function key perform POKEs 
fl POKE 520,PEEK (FA) 
POKE 521,1 
f2 POKE 520,PEEK (FA + 16) 
POKE 521,17 
3 POKE 520,PEEK (FA + 32) 
POKE 521,33 
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When you “type” a function key in this way, your program 
will INPUT it before any of the characters in the keyboard 
buffer or the pushkey buffer. 


You cannot “type” a function key by POKEing it into the 
pushkey buffer. If you try, your program will INPUT the ASCII 
code that represents the function key (#21, #22, or #23) 
instead of the function key's current definition. 


THE STOP/SPEED KEY 


The HHC’s LCD rotation speed and menu speed are control- 
led by the value at location 535. This location may be 
PEEKed or POKEd. The value’s meaning is: 





value STOP/SPEED setting 
10 1 (slowest setting) 
9 2 
8 3 
7 4 
6 5 
5 6 
4 7 
3 8 
2 9 
1 0 (fastest setting) 
0 Faster than fastest STOP’SPEED setting 


DATE AND TIME 


The HHC maintains a the current date and time in a 5-byte 
memory area at locations 526 through 530. You can PEEK at 
this area to get the current date and time. 


The HHC’s timer is not directly available to you: locations 
526 through 530 contain a copy of it. This has two consequ- 
ences: 

1. The date and time that you can PEEK are not absolutely 
accurate. They are updated periodically by the HHC. The 
updating schedule is too complicated to explain here in 
detail, but at a minimum, the date and time are updated 
whenever one of the following events takes place: 


a. The cursor flashes on (every 0.7 seconds, when the 
cursor is flashing). 


b. When a character is input to the HHC from the 
keyboard or from any peripheral. (This refers to the 
physical event of inputting a character, not to the prog- 
ram's execution of an INPUT statement, which may 
happen much later.) 


c. Approximately every 9 hours. 


2. You cannot POKE the date and time. If you try, the value 
you POKE will be wiped out the next time the HHC 
updates the timer. 


Format Of the Date and Time 


The date and time are kept in a single integer number that is 
5 bytes long. The value of this integer is the number of clock 
units (one clock unit = 1/256 second) from the beginning of 
January 1, 1980, to the present. The bytes of the date and 
time count the following units of time: 


location counts units of 


526 1/256 second 
527 seconds 
528 256 seconds 


529 65,536 seconds 
(approximately 18 hr., 12 min.) 


530 16,777,216 seconds 
(approximately 194 days, 4 hr.) 


One reasonable way to use the date and time is to define a 
5-element array and move each byte of the value into one 
element: 


eme 





Then you can write a variant of our day-of-year calculator to 
convert the 5-element array into a meaningful date and time. 


You can simplify the task somewhat by ignoring the first byte 
of the time, since the time will seldom be accurate to more 
than a second. 


If you are concerned oniy with elapsed time, you can build 
two arrays like Tl, above, one for a start time and one for an 
end time. Then you can “subtract” one array from the other. 
Do this by analogy with the ordinary process of subtracting 
two numbers by hand; treat each element of the array as a 
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“numeral” and borrow from the next greater element when 
necessary: 





After performing this subtraction, the result should represent 
a value small enough to hold in a numeric variable without 
loss of precision: 








ROTATION MODE 


The LCD's rotation mode is controlled by the value at 
location 534. The value’s meaning is: 


value _ rotation mode 


0 fill mode. The LCD is filled with text, left to 
right, as fast as a program can display it. 
After the LCD is full, the HHC erases 
everything and starts filling the LCD again. 


1 fill-and-rotate mode. The LCD is filled with 
text as in fill mode. After the LCD is full, the 
HHC shifts characters off the left end to make 
room for new characters on the right. (This is 
the HHC’s normal mode of operation.) 


2 rotate mode. Characters are rotated onto the 
LCD from the right edge, even when the LCD is 
not full of text. 


Note that the rotation mode is not reset by the CLEAR key. 


8-9 


VARIABLES AND ARRAYS 


Locations of Variables and Arrays 


For some kinds of mathematical calculations it is useful to be 
able to PEEK and POKE the parts of a numeric variable 
directly. 


For example, if you must multiply two numbers together and 
first want to determine whether the product will overflow, you 
can PEEK at the two numbers’ exponents, add them, and 
determine whether the sum is over or near the maximum. 
(See the definition of the trigonometric function ATAN2 in 
Chapter 2 for an example of this.) 


Basic stores all variables consecutively in memory. It stores 
all arrays consecutively in another part of memory. 


The locations that point to the variable and array areas are: 


location contents‘? 


200-201 Address of beginning of variable area. Note, 
this address changes when you edit your 
stored program. 


202-203 Address of end of variable area and 
beginning of array area. Note, this address 
changes when you edit your stored program 
or use a new variable. 


204-205 Address of end of array area. Note, this 
address changes when you edit your stored 
program, or use a new variable or array. 





{2} _ In each two-byte integer value or address, the first byte is the 
least significant and the second byte is the most significant. Thus, 
you can reconstruct the address of the beginning of the variable area 
(for example) like this: 


AN=FPRER. SEE 
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Formats of Variables 


Variables are stored in the variable area in the order that the 
program first refers to them. Each variable occupies 7 bytes. 


Anumeric variable has the following format: 


byte contents 
0 First character of the variable name, in 
ASCIl. 
| Second character of the variable name, in 


negative ASCII!*! If the name is one 
character long, PEEK(byte 1) = 0. 


2-6 Value of the variable in numeric format (see 
the Format of a Numeric Value section in the 
following text.) 

An integer variable has the following format: 
byte contents 


0 First character of the variable name, in 
negative ASCII. 


1 Second character of the variable name, in 
negative ASCII. If the name is one character 
jong, PEEK(byte 1) = 128. 


2-3 Value of the variable in two’s complement 
binary form: 


4-6 Unused. 
A string variable has the following format: 
byte contents 


(0) First character of the variable name, in 
negative ASCII. 


1 Second character of the variable name, in 
ASCII. If the name is one character long, 
PEEK(byte 1) = 0. 


2 Length in characters of the string value. 





3} _ To convert negative ASCII to ordinary ASCII, substract 128 
from the value returned by PEEK. 
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3-4 Address of the first character of the string 
value. The characters in the value are stored 
consecutively. Note, this address may change 
any time you create a new string variable or 
array, or change the value of an existing 
one. 


5-6 Unused. 


Formats of Arrays 


Arrays are stored in the array area in the order that the 
program first refers to them. 


Ail arrays have the following format: 
byte contents 


0-14 Array name, in ASCII and/or negative ASCII. 
The conventions used to indicate the type of 
the array are the same as for variables. 


2-3 Length of this array, including the name, 
length field, etc. Add this length to the 
address of this array to get the address of 
the next array (if any). 


4 Number of dimensions. 


Dis Size of each dimension. Each size field is two 
bytes long. The sizes of the dimensions are 
given in reverse order, i.e., the rightmost 
dimension is given first, the leftmost last. 


varies After the dimensions come the elements. In 
multi-dimensional arrays, the first element 
varies fastest. For example, in an array XY 
dimensioned (1,1), the elements would be 
stored in the order (0,0), (1,0), (0,1), 
(1,1). 


In a numeric array, each element is five bytes long, and is 
Stored in variable format (see below). 


In an integer array, each element is two bytes long, and is 
stored in two’s complement binary notation. 


in a string array, each element is three bytes long. The first 
byte gives the length in characters of the value of the 
element. The second and third bytes contain the address of 
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the first character of the element. Note, this address may 
change any time you create a new string variable or array, or 
change the value of an existing one. 


Format Of a Numeric Value 
if a numeric value is expressed as 
n= s«m2e 
where 
Ss = the sign, +1, 
m = the mantissa, in the range 1.0<=m<2.0, 
e = the exponent, in the range +127, 
then the variable’s format is: 


bytes(bits) contents 


0(0)-0(7) 128+ ein binary form. If this field is 0, 
then the numeric value is 0, even if 
m=0. 


1(0) Sign bit. 
If s=-1 (n<0), the bit is on. 
lf s=1 (n> =0), the bit is off. 


1(1)-4(7) m-1.0. Stored as a 31-bit binary fraction 
with the “binary point” before the first 
bit. 


Other Useful Addresses 


Here are some other useful addresses relating to variables 
and programs: 


location contents 


71-72 Address of the variable or array element most 
recently referred to. If the variable or 
array is numeric or integer, this is the — 
address of the value. If it is string, this is 
the address of the length byte. Note: in 
an assignment statement of the form 
XX = PEEK(71) + 256*PEEK(72), the “variable 
most recently referred to” is XX! 


212-213 Line number of the line currently being 
executed. In immediate mode, the “line 
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number” is greater than 63,999 (the largest 
valid value). 


214-215 Line number of the line that was being 
executed when the most recent of the 
following events occurred in deferred mode: 
1. Execution of a STOP statement. 

2. Execution of an END statement. 
3. Program interrupted by the C1 key. 


218-219 Line number of the DATA statement currently 
being read. 


Finding a Variable’s Value 


The most convenient way to find a variable’s value is to refer 
to the variable, then PEEK at location 71-72 to get the 
address of the value. For example, the following code may 
be used to assign EX the value of the exponent of VL: 





Note that this statement would not work if line 500 said 
‘VL=VL, since line 510 assigns EX the address of itself. 
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CHAPTER 9: ASCII CHARACTERS 


The character set used by the HHC is listed in order of the 
numbers that represent the characters in ASCII notation. 


CONTROL CHARACTERS 


The following table lists characters #0 through #31. These 
characters are control characters, rather than graphic char- 
acters; that is, their customary function is to perform a 
control function on an output device, rather than to display a 
symbol like A or ‘?’. 

The meanings of the columns in the table are: 


@ Numeric value: the number used to represent this char- 
acter in the HHC’s memory. If NV is the numeric value of 
the character, then CHR$(NV) is the character. 

@ HHC name: the name, or description, used to identify this 
character in the HHC system. 

e ASCII name: the name or description used to identify this 
character in “pure” ASCII. 

®@ HHC key: key on the HHC keyboard that inputs this 
character. 


@ HHC graphic: the graphic symbol that represents this 
character when the character is displayed on the LCD. 
For characters that have a control function, you must use 
the ‘ESCDC’ escape control sequence to display the 
character. 

e@ LCD action: control function performed by this character 
when it is sent to the LCD. If this column is empty, the 
character has no control function; it displays the graphic 
symbol listed under ‘HHC graphic’. 


numeric HHC ASCII 


value name name 


NUL, Null 

SOH, Start of heading 
STX, Start of text 
ETX, End of text 


EOT, End of transmission 

ENQ, Enquiry 

ACK, Acknowledge 
Rotate; Bell BEL, Bell 


NO QOn~+~oO 


Backspace BS, Backspace 
HT, Horizontal tab 

Line feed LF, Line feed 

vO VT, Vertical tab 


a 
25 Om 
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‘ss 
GS —) 
numeric HHC ASCII = numeric HHC HHC LCD 
value name name © = _value key graphic action 
12 Formfeed FF Form feed <= * 20. HELP 
13 Enter CR, Carriage return Cc re) 21 f1'™ 
14 Stop Speed SO, Shift out : 22° « f2 He 
15 Sl. Shift in tk a) 23 3. 
16 DLE. Data link escape 3 24 
17 DC1. Device control 1, XON & s 25 
18 DC2, Device control 2 26 
19 DC3, Device contro! 3. XOFF & —) 27 ay an escape 
control sequence. 
20 ~=Help DC4. Device control 4 : 
21 Ot NAK. Negative acknowledge & 2 28 
22s SYN, Synchronous idle  ) 29 
23.3 ETB. End of transmission block Long ; = 
24 CAN. Cancel eS 2 
25 EM. End of medium 4a 
26 SUB. Substitute 
27. (Esse. ERC. Escape . DISPLAYABLE CHARACTERS 
ag Be pee i oes e — The HHC’s use of characters #32 through #126 conforms 
29 GS. Group serareta? PY exactly to the ASCII standard. 
30 RS, Record separator sd : 
31 US. Unit separator a ainsi Abeta 
& ey 
~ value character name 
a , cd 32 space 
3 ! i 
numeric HHC HHC LCD a 2 - ! Ta 
value key graphic action 9 35 bg Bound. sich 
9 e ; 
s = & Se 
3 ~ 38 & ampersand 
> & 39 ‘ apostrophe 
3 - & 40 ( left parenthesis 
6 so 41 ) right parenthesis 
. s 42 * asterisk, star, or “times” sign 
7 ROTATE beep e r) 43 : aus cis 
8 Backspace cursor: 
erase character under e L-) oe ' ed es Pane ; : 
cursor after backspace. - ypnen, dash, or minus sign 
9 i -) 46 ‘ period 
10 a e 47 / slash 
11. «10 KE . & Pe ; 
| 49 1 
12 Le 
13. ENTER Erase LCD: move e = J oe a 
; cursor to left edge. 2 
14. STOP SPEED'" ff , 
: ane 
a | 54 6 
16 
55 7 
17 
18 | en » 
19 = 56 8 
ae 57 9 
e a 58 : colon 
''. This key has an immediate function in Basic, and so cannot he. 9 ” ; Semicelon 
normally be read by GET. Note that none of the control characters 
#0 through #31 can be read by INPUT. ace J 
a8 y 
9-2 , @ 9-3 
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numeric HHC keybd & =) numeric HHC keybd 
value character name 7 =) value __ character. name 
60 é left angle bracket or “less than" sign & = 112 p 
61 ss equal sign — ) 113 q 
62 : right angle bracket or “greater than” sign & 114 r 
63 ? question mark 2 115 s 
64 (tt & 116 t 
65 A —) 117 u 
66 B & . 118 v 
67 Cc —} 119 w 
D & ' 120 
68 ‘ x 
69 E ¢ @ tat y 
70 F z 
71 G e rc ] 123 ! left brace 
72 H 124 | vertical bar 
73 e ? 125 \ right brace 
74 J 126 i tilde 
78 , - 2 
76 L 2 
7 M & ~ _ ADDITIONAL CHARACTERS 
78 N ’ 
79 re) e The HHC uses characters from #127 up as displayable char- 
ss i a ce ] acters and control characters. 
81 Q = ry In “pure” ASCII, character #127 represents the control char- 
a B eo acter “delete.” Characters above #127 are undefined. 
84 T » 9 numeric HHC HHC HHC LCD 
85 U { value name key graphic action 
86 Vv e ® a 
87 Ww r) 127 = “insert” cursor 
88 x & 128 uparrow a? t 
89 Y e s i 
90 Z 129 leftarrow e & Backspaces cursor; does not 
91 | left bracket g disturb character under cursor 
e after move. 
92 \ backslash r=) _ 
93 | right bracket e . 130 rightarrow 9 + Advances cursor; does not 
94 A caret disturb character that was 
95 a underscore e s under cursor before move. 
96 \ grave 131 downarrow wo! s 
ol e ® : 
98 b 132 ‘AM’ symboi INSERT or 
99 c e 2 
133. “PM” symbol DELETE’?! La 
100 J e ® 7 ‘ 
101 e 4 134  superscriptM 4} ie 
102 f i 
103 g e Ps 135 divisionsign a 
104 h = 
105 i {2}. j 
s6n ~ ® INPUT reads this character as ENTER. 
107 K ; : . 1 
e 9 '3}_ INPUT cannot read this character; it performs its usual editing or 
108 | contro! function. 
109 m te ® 
110 n d ; 
111 ° c rv {4!_ INPUT reads this character as SPACE. 
9-4 « @ 9-5 
c.® 

















numeric — HHC HHC —-HHC LCD CHAPTER 10: ERRORS 
value name key = graphic action 
136 “times” sign {4} 


ERROR MESSAGE FORMAT 


When Basic detects an error in immediate mode, it beeps 
and displays a message saying 


137 blockcursor SEARCH? i 


138 “delete” cursor Ci 





139 ‘a'with umiaut crs! «Except when read by GET, causes 
‘preak” in execution of the +E 
program that is running. at 
140 ‘o'withumlaut C2. otk where xx is one of the two-character codes described below. 
141 ‘u'withumlaut cs When Basic detects an error in deferred mode, it beeps and 
aa displays a message saying 
142 ‘n'withtilde C4 


xx ERROR IM re 





where xx is a two-character code and nnnn is the line 
number of the tine that was being executed when the error 
occurred. 


ERROR CODES 


BS - Bad Subscript 


You tried to use an array element that is outside the 
dimensions of the array. This message can also occur if 
you use the wrong number of subscripts. 


CN - Can't Continue 


You tried to CONTinue a program when you have not 
done a RUN, after execution was interrupted by an error, 
or after you edited the program. 


DD -- Duplicate Dimension 


You tried to define an array with DIM after the array was 
already defined. This error often occurs because the 
array was defined implicitly (by using one of its elements) 
before the DIM statement was executed. 


FC -- Function Cail 


You gave a function an argument whose value was out of 
range. Check the description of the function in question 
for the permissible range of values. 
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ID -- {ilegal Direct 


You tried to execute a statement in immediate mode that 
is only allowed in deferred mode. 


10 -- I/O Error 


First possible cause: you tried to do an I/O operation ona 
LUN that was not successfully ATTACHed to a peripheral 
device. Note that an unsuccessful ATTACH does not 
produce this error; the first /O operation on the LUN 
produces it. 


Second possible cause: an I/O operation failed to com- 
plete successfully. An I/O operation may fail to complete 
because the operation is illegal (e.g., an INPUT operation 
on a LUN attached for output), or because the device is 
improperly set up or out of order. 


This error can occur if you try to do an I/O operation on a 
LUN that has been “unattached” by a POKE. 


LS -- Length of String 


You tried to use the concatenation operation, ‘+’, to 
create a string more than 255 characters long. 


NF -- NEXT without FOR 


Basic encountered a NEXT statement that did not corres- 
pond to a FOR/NEXT loop it was executing. This can be 
caused by a NEXT that does not match any FOR; a NEXT 
with the wrong variable name; or a GOTO that passes 
control to a line inside a FOR/NEXT loop without execut- 
ing the FOR statement. 


OD -- Out of Data 


You executed a READ statement, and no DATA items 
remained for it to read. 


OM -- Out of Memory 


There is not enough memory for your program to run. This 
can be caused by any combination of the following 


ta 


conditions: the program is too large; the program requires too 
much memory for variables and arrays; the program has too 
many nested FOR/NEXT loops; the program has too many 
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nested GOSUBs; or an expression is too complicated. 


OV -- Overflow 


You tried to perform a calculation whose result was too 
large to be represented in Basic’s numeric format. The 
largest number Basic can represent is approximately 
1.70141+10% . 


Note that underflow does not produce an error in Micro- 
soft Basic. It just returns a zero result. 


RG -- Return without GOSUB 


You tried to execute a RETURN without having executed 
a GOSUB. This is often caused by passing control to a 
subroutine with GOTO instead of GOSUB, or by letting 
control fall into a subroutine instead of passing it some- 
where else. 


RT -- Run Time Error 


This message indicates an error in an operation which 
Basic requested one of the HHC’s intrinsic programs to 
perform. It is often associated with an invalid 1/O opera- 
tion. 


SN -- Syntax Error 


You made an error in writing a statement, such as missing 
parentheses in an expression, use of a reserved word ina 
variable name, missing elements in a statement, etc. 


ST -- String Formula Too Complex 


You tried to use a string expression too complex for Basic 
to process. Break it up into two or more shorter express- 
ions. 


TM -- Type Mismatch 


An assignment statement tried to assign a string value to 
a numeric variable, or vice versa; or an operator found a 
value of the wrong type; or a function found an argument 
of the wrong type. 
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UF -- Undefined Function 
You tried to use a function that has not been defined. 


US -- Undefined Statement 


You tried to go to a non-existent line number with IF, 
GOTO, or GOSUB. 


/0 -- Division by Zero 


You tried to divide a number by zero. Note that dividing 
zero by zero produces this error. 
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FRIENDS AMIS, INC. 


The program described in this document is furnished under a 
license and may be used, copied, and disclosed only in 
accordance with the terms of such license. 


Friends Amis, Inc. (“FA’) EXPRESSLY DISCLAIMS THE IM- 
PLIED WARRANTIES OF MERCHANTABILITY AND FIT- 
NESS FOR USE FOR A PARTICULAR PURPOSE RE- 
SPECTING THE HHC SOFTWARE PROGRAM AND 
MANUAL. THE PROGRAM AND MANUAL ARE SOLD “AS 
IS”. THE IMPLIED WARRANTIES OF MERCHANTABILITY 
AND FITNESS FOR USE FOR A PARTICULAR PURPOSE 
AS TO THE MEDIUM ON WHICH THE SOFTWARE IS RE- 
CORDED ARE LIMITED TO SIXTY (60) DAYS FROM THE 
DATE OF LICENSING BY THE INITIAL USER OF THE PRO- 
DUCT AND ARE NOT EXTENDED TO ANY OTHER PARTY. 


USER AGREES THAT ANY LIABILITY OF FA HEREUN- 
DER, REGARDLESS OF THE FORM OF ACTION, SHALL 
NOT EXCEED THE LICENSE FEE PAID BY USER TO FA. 
FA SHALL NOT BE LIABLE FOR INDIRECT, SPECIAL OR 
CONSEQUENTIAL DAMAGES, SUCH AS, BUT NOT LI- 
MITED TO, LOSS OR INJURY TO BUSINESS, PROFITS, 
GOODWILL, OR FOR EXEMPLARY DAMAGES, EVEN IF 
FA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGES. 


FA will not honor any warranty when the product has been 
subjected to physical abuse or used in defective or non- 
compatible equipment. 


The user shall be solely responsible for determining the 
appropriate use to be made of the program and establishing 
the limitations of the program in the user’s own operation. 


§ 
An: important note: Good data processing procedure dic- 
tates that the user test the program, run and test sample sets 
of data, and run the system in parallel with the system pre- 
viously in use for a period of time adequate to insure that 
results of operation of the computer or programs are satisfac- 
tory. 


